Chapter 02 · StoryCam Development Narrative
文档基线、架构决策与实现计划
本 session 把 StoryCam 从一份较粗的产品设计，推进为可执行的中文产品规格、工程文档体系和 Phase 0/Phase 1 开发计划。
本 Session 摘要
- 用户指出 gstack 产出的 StoryCam 产品设计不够详细，要求使用 spec-driven development 方式迭代，并明确需要中文版本。
- 本次讨论补齐了 MVP 的关键产品约束：故事世界确认、1-3 个核心分镜组、扩展分镜、Seedance 2.0 clip、真实合成 final work、账号内保存和预览。
- 工程基线从“前端原型”扩展为完整 Web 产品架构：Next.js、Supabase Auth/Postgres/Storage、Vercel AI SDK、OpenRouter、Seedance 2.0。
- 借鉴 OpenAI Harness Engineering 的思想，项目文档被整理为短入口、索引化 docs、active exec plans、generated contracts、references 的结构。
- 用户要求先完成文档型任务，不急着写代码；因此先完成 Task 2 开发者契约文档，再完成 Task 1 工程文档基线校准。
- 会话末尾确认下一步将进入代码实现，第一项是 Task 3：Scaffold Web app；但用户随后提醒
AGENTS.md和ARCHITECTURE.md还需要继续动态对齐。
时间线
“docs/product/storycam-film-machine-design.md 这个是 gstack 出的产品设计文档，但是我觉得不详细，你可以使用 $spec-driven-development 来迭代。需要中文版本的。”
采用规格先行的方式处理：先不进入代码，而是把 StoryCam 的产品目标、用户路径、生成阶段、确认节点和产物结构写成更可执行的中文规格。
“剧本 + 人物资产 + 场景资产、分镜脚本 + 1-3 个核心分镜组、拓展分镜，这些具体的实现方法，或者调用哪些 ai 模型没有写，是在这步写还是到 plan 里写？”
把“产品规格”和“实现计划”的边界拆开：规格里定义用户可理解的产物、阶段和体验结果；计划里补具体技术框架、provider contract、模型调用方式、失败路径和验证命令。
“核心分镜组的数量，应该由计划生成的视频长度来自动判断生成一组、两组还是三组。”
“Phase 1 允许用户上传照片。”
“故事世界确认默认更像短剧本。”
“第一版真实视频生成成功后不支持分享，只支持本地保存和预览。”
“真实合成 final video。”
“由最强核心分镜图承担封面。”
“如果 Seedance 2.0 输出质量不稳定，第一版救援路径优先是重拍。”
“不允许导出 Shanyin-style shot data，Shanyin-style 都是后台设计，用户需要知道核心方案。”
把这些回答固化为 MVP 决策：核心分镜组数由时长自动判断，扩展分镜默认服务于父分镜组，不单独触发视频生成；final work 必须是真实合成视频；Shanyin 方法只作为内部导演脑，不暴露专业表格给普通用户。
“使用 $planning-and-task-breakdown，在 docs/engineering 基础上进行详细的规划。旧的计划可以迭代，不要完全保留。”
用任务拆解方式重写 active implementation plan：按依赖顺序组织 Phase 0 工程契约、Web scaffold、env 校验、Auth、artifact schema、Supabase、provider、job、UI 和 QA。旧计划不被机械保留，而是被迁移、修正和吸收。
“我看没有后端服务和数据库的一些设计？”
识别到原计划偏前端和产品流，缺少后端服务、数据模型、作业生命周期和权限边界。后续计划因此补入 API contract、repository layer、RLS、Storage bucket、job lifecycle、privacy logging 等内容。
“数据库建议直接使用 supabase，然后后端的 ai 服务用 vercel ai sdk，具体一些生文和生图的模型用 openrouter 里的模型，你是不是还有考虑图片和视频在云端的存储。还是要有账号登录（首选 google 登录），使用 supabase 里的就行。”
采纳这组技术决策：Supabase Auth 负责 Google 登录，Supabase Postgres 负责元数据和 RLS，Supabase Storage 负责上传图片、生成 clip、final work 和封面；Vercel AI SDK 编排文本、多模态、图像 provider，OpenRouter 作为模型入口，Seedance 2.0 通过视频 provider adapter 接入。
“借鉴这篇 blog 里的核心思想调整下 agents、docs 等结构，便于后续的开发。”
用户给出目标结构：AGENTS.md、ARCHITECTURE.md、docs/design-docs、docs/exec-plans、docs/generated、docs/product-specs、docs/references 以及 DESIGN.md、FRONTEND.md、SECURITY.md 等顶层指南。
参考用户提供的 OpenAI Harness Engineering 文章，把仓库文档重组为“短入口 + 索引 + active plans + generated contracts + references”。核心思想是让 repo 自己成为长期记忆，而不是依赖一次性聊天上下文。
docs/README.md、AGENTS.md 和 ARCHITECTURE.md 快速进入正确上下文。“先做文档型的吧 Task 2，文档型的都做完再碰代码。”
优先完成 Task 2：补齐开发者契约文档。产出包括 API contract、provider contract、job lifecycle、privacy logging、local dev 说明，并把 mock/real mode、env vars、route contract、隐私日志规则写清楚。
“那做 task1。”
完成 Task 1：同步工程文档基线。重点检查并标记了“不支持分享链接”“final work 必须真实合成”“测试关键路径从 save/share 改为 account save/preview”。
“那下一步是要进行代码实现了么？”
确认文档型 Task 1、Task 2 已完成，下一步进入 Task 3：Scaffold Web app。计划从 Next.js App Router、TypeScript、Tailwind、基础脚本和 StoryCam Phase 1 shell 开始。
“现在改了不少 docs，但是我看 AGENTS.md 和 ARCHITECTURE.md 没有动态的调整。”
开始读取 AGENTS.md、ARCHITECTURE.md、docs/README.md 和 generated contracts，准备把这两个顶层入口继续对齐到最新 docs 结构与 Phase 0 决策。但该轮被用户中断，没有产生最终修改。
关键时刻
产品产物必须先成形，再生成视频
当时的问题：原设计没有清楚写出剧本、人物资产、场景资产、分镜脚本和核心分镜组如何实现。
为什么重要：如果直接生成视频，StoryCam 会变成普通 prompt-to-video 工具，用户感受不到私人故事世界被逐步搭建。
最终处理：确认 MVP 必须保留“故事世界确认”阶段，再进入核心分镜组和 Seedance clip 生成。
Supabase 成为账号、数据和媒体基座
当时的问题：计划缺少后端服务、数据库、云端媒体存储和账号体系。
为什么重要：用户会上传照片和生成私人视频，必须有用户隔离、RLS、私有 bucket、短期预览 URL 和删除链路。
最终处理：确定 Supabase Auth + Postgres + Storage；Google 登录优先，第一版只做账号内保存和预览。
Vercel AI SDK + OpenRouter + Seedance 分层
当时的问题：生文、生图、生视频的模型和调用方式没有写。
为什么重要：模型调用如果直接散在 UI 或 route 中，会让测试、替换、成本控制和隐私脱敏都变困难。
最终处理：文本、多模态、图像走 Vercel AI SDK 和 OpenRouter provider adapter；视频走独立 Seedance 2.0 adapter；mock mode 默认可跑通。
第一版不做分享，final work 必须真实合成
当时的问题：旧文档里存在分享链路和“单 clip 也可以是 final work”的歧义。
为什么重要：分享会引入权限、撤销、安全和产品范围膨胀；final work 如果只是文案或 clip 引用，会削弱作品完成感。
最终处理：Task 1 验收明确：不生成分享链接；即使只有一个 clip，也要生成新的 final work 文件并写入 Supabase Storage。
先完成文档型任务，再进入代码
当时的问题：文档结构和工程契约还在变动，直接写代码会放大返工。
为什么重要：StoryCam 同时涉及产品体验、AI provider、存储、安全和异步 job，先定契约能降低实现混乱。
最终处理：用户明确要求先做 Task 2 和 Task 1；代码实现被推迟到文档基线稳定之后。
工程证据
文件与结构变更
- 新增 / 重写入口：
AGENTS.md、ARCHITECTURE.md、docs/README.md。 - 产品文档迁移到：
docs/product-specs/。 - 设计文档迁移到：
docs/design-docs/。 - 执行计划迁移到：
docs/exec-plans/active/。 - 生成契约文档新增：
docs/generated/api-contract.md、provider-contract.md、job-lifecycle.md、privacy-logging.md、db-schema.md。 - 参考资料新增 / 迁移：
docs/references/openai-harness-engineering.md、docs/references/local-dev.md、Shanyin director reference。
验证命令
rg -n "STORYCAM_GENERATION_MODE|GenerationJob|redaction|/api/story-world|/api/final-work" docs：用于验证 Task 2 契约覆盖。rg -n "私密分享|分享链接|share|一个 clip 也可以是 final work" docs：用于验证 Task 1 没有残留旧产品承诺。git diff --check -- AGENTS.md ARCHITECTURE.md docs：用于检查文档 diff 是否存在尾随空白等问题。
状态记录
- 完成Task 1：同步工程文档基线。
- 完成Task 2：补齐开发者契约文档。
- 未产生本 session 未记录 PR、commit、CI、release 或 deploy 结果。
- 未确认
AGENTS.md与ARCHITECTURE.md的二次动态调整在用户中断前尚未完成。
架构基线
- Frontend：Next.js App Router + TypeScript + Tailwind。
- Auth：Supabase Auth，Google 登录优先。
- Database：Supabase Postgres + RLS。
- Media：Supabase Storage private buckets。
- AI：Vercel AI SDK + OpenRouter provider adapters。
- Video：Seedance 2.0 behind
VideoGenerationProvider。 - Final work：真实合成视频文件，账号内预览和保存。
对外讲解用总结
这一章可以理解为 StoryCam 从“一个有吸引力但还比较松散的 AI 视频产品设想”，走向“可被工程团队持续开发的项目系统”的过程。我们没有急着写前端页面，而是先把用户体验里的每个关键产物讲清楚：用户输入私人想法和照片，系统先生成短剧本式故事世界、人物和场景资产，用户确认后再生成 1-3 个核心分镜组，最后每组对应一个 Seedance 2.0 视频片段，并被真实合成为最终作品。
这一步对 StoryCam 很重要，因为它同时解决了产品边界和工程边界：第一版不做公开分享，不导出专业 Shanyin 镜头表，不把扩展分镜误当成独立视频调用；同时明确 Supabase、Vercel AI SDK、OpenRouter、Seedance 2.0、Storage、RLS、job lifecycle 和隐私日志的职责。它连接了前面的产品愿景，也为后面的 Task 3 Web app scaffold、Auth、数据库、provider adapter 和 UI 实现铺好了路。
后续事项
- 已完成中文产品规格迭代：补齐故事世界、核心分镜组、扩展分镜、clip 和 final work 的 MVP 语义。
- 已完成工程计划重组：active implementation plan 和 test plan 已对齐“不分享、账号内保存/预览、真实 final work”。
- 已完成开发者契约文档：API、provider、job lifecycle、privacy logging、local dev 基线已形成。
- 待确认
AGENTS.md和ARCHITECTURE.md需要继续动态调整，确保它们反映最新 docs 结构和 Phase 0 决策。 - 待确认final work 账号内预览具体使用 signed URL、authenticated proxy，还是两者都支持。
- 后续开发进入 Task 3：Scaffold Web app，创建 Next.js App Router + TypeScript + Tailwind 项目骨架。
- 后续开发继续 Task 4 / Task 4A：环境变量校验、mock/real mode、Supabase Auth 和 Google 登录。
- 后续开发随后实现 artifact schemas、Supabase schema/RLS/Storage、provider adapters、job state machine 和端到端 StoryCam UI。
敏感信息处理：本章节没有包含 API key、token、secret、完整 DSN、cookie、签名 URL、用户私密素材或原始 provider payload。